feat(react-headless-components-preview): add Popover & positioning by mainframev · Pull Request #36006 · microsoft/fluentui

mainframev · 2026-04-20T00:51:52Z

Adds a headless Popover (Popover, PopoverTrigger, PopoverSurface) to the @fluentui/react-headless-components-preview package, positioned via the native CSS Anchor Positioning API instead of floating-ui

Feature with v9 `@fluentui/react-popover`

v9 feature	Status
`open` / `defaultOpen` / `onOpenChange`	✅
`openOnHover` + `mouseLeaveDelay`	✅
`openOnContext` (right-click, cursor-anchored)	✅
`withArrow` (+ consumer-owned arrow CSS via `[data-placement]`)	⚠️ User provides styles for arrow based on data-placement and data-arrow attributes
`trapFocus` + `aria-modal` / `role="dialog"`	❌ Not implemented (TBA)
`disableAutoFocus`	✅
`closeOnScroll`, `closeOnIframeFocus`	✅
`inline` (skip top-layer)	⚠️ v9: skips the `<Portal>` wrapper - DOM placement only, positioning math unchanged. Headless: skips HTML Popover API top-layer promotion, also changes the overflow boundary CSS `position-try-fallbacks` flips against (viewport → nearest + scroll port / containing block)
`mountNode` (portal target)	✅
Nested popovers (per-instance Escape / dismiss)	✅
`positioning.position` + `positioning.align`	✅
`positioning.offset` (number or `{ mainAxis, crossAxis }`)	✅
`positioning.coverTarget`	✅
`positioning.fallbackPositions`	✅
`positioning.autoSize` (`true` / `'width'` / `'height'`)	❌ Not implemented (TBA)
`positioning.overflowBoundary`	❌ Not implemented (TBA)
`positioning.overflowBoundaryPadding`	❌ Not implemented (TBA)
`positioning.overflowBoundaryRect`	❌ Not implemented (TBA)
`positioning.matchTargetSize: 'width'`	✅
`positioning.strategy: 'absolute' \| 'fixed'`	✅
`positioning.pinned`	✅
`positioning.target` (custom anchor)	✅
`positioning.positioningRef` (imperative `setTarget`)	✅
`flipBoundary`	❌ Not implemented (TBA)
`arrowPadding`	➖ Configurable on user side via styles
`shiftToCoverTarget`	❌ Not implemented (TBA)
`onPositioningEnd`	➖ Native API has no "settle" event
`disableUpdateOnResize`	➖ Native anchor positioning + targeted usage is always-on
`useTransform`	➖ Native anchor positioning doesn't use transform, no conceptual equivalent

Related Issue(s)

Partially implements RFC: Headless Components (@fluentui/react-headless-components) #35984

github-actions · 2026-04-20T01:02:50Z

Pull request demo site: URL

github-actions · 2026-04-20T01:59:41Z

📊 Bundle size report

✅ No changes found

dmytrokirpa · 2026-04-23T14:12:01Z

+
+export type PositioningReturn = {
+  targetRef: React.RefCallback<HTMLElement>;
+  containerRef: React.RefCallback<HTMLElement>;


should this be surfaceRef or is it for consistency with v9?

yes, for consistency

dmytrokirpa · 2026-04-23T14:16:16Z

+function mountHook(options: PositioningProps = {}) {
+  const resultRef = React.createRef<{ current: PositioningReturn }>();
+  const Capture = () => {
+    const result = usePositioning(options);


nit, but we can probably type-cast once if it's really needed

Suggested change

const result = usePositioning(options);

const result = usePositioning(options) as unknown as { current: PositioningReturn };

dmytrokirpa · 2026-04-23T14:19:21Z

+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
+    expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');


nit, but we can use the https://github.com/testing-library/jest-dom#tohavestyle to make it a bit cleaner

Suggested change

expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');

expect(node).toHaveStyle({ positionArea: 'block-end span-inline-end' });

dmytrokirpa · 2026-04-23T14:20:38Z

+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.position).toBe('absolute');


nit, but can be combined to one assertion for all styles

dmytrokirpa · 2026-04-23T14:27:07Z

+  const childProps = (child?.props ?? {}) as Record<string, unknown>;
+
+  const triggerChildProps = {
+    'aria-expanded': `${open}` as 'true' | 'false',


Why don't we use the popovertarget attribute https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#html_attributes?

current implementation uses showPopover() and I found it more suitable as we need to also show Popover on hover (v9 canonical Popover has that feature), have it controlled and uncontrolled, mouseLeaveDelay for openOnHover etc

dmytrokirpa · 2026-04-23T14:32:47Z

+
+  const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
+
+  useOnClickOutside({


just to confrim, did you check if Popover API has this functionality out-of-the-box?

it does, but only when popover has popover='auto' / popover attribute, which has native dismiss on Esc and overlay click, great that it works also with nested popovers, but in current implementation it uses manual, which does not have such functionality out of the box, because we need multiple non-nested Popovers to be opened. I think auto will be a great fit to Tooltip

We may need to set auto as the default option and offer a way to switch to manual + custom logic when advanced features are required. I'm not entirely sure how this would work yet, but we might need a similar approach for this and positioning as well

maybe we should split this into two separate components (as subcomponents of Popover). Embedding logic like useOnClickOutside and useOnScrollOutside directly in hooks doesn't seem appropriate, especially when auto is only used to support dismissing an already open Popover. This approach as a default also diverges from v9 Popover behavior, where multiple Popovers can be open simultaneously

…n native CSS anchor positioning

…ybook stories

…n spec-pure CSS anchor positioning

…and unsupported positioning props

…ation-1 strip-down

…assertions to toHaveStyle

Adds a PopoverAuto component that renders its surface with `popover="auto"` instead of `popover="manual"`, so light dismiss (Escape, click-outside, popover-stack peer dismissal) is handled by the browser rather than React. Implementation: - Extracts a shared internal hook `useInternalPopover(props, popoverType)` in usePopover.ts. Both the existing `usePopover` (manual) and a new `usePopoverAuto` are thin wrappers that fix the popoverType. - Sets the `popover` attribute to the actual mode value when calling `showPopover()`. - In auto mode: disables `useOnClickOutside` / `useOnScrollOutside` and attaches a `toggle` event listener on the surface to mirror the browser's open/closed state into React and fire onOpenChange. - Plumbs `popoverType` through PopoverContextValue so PopoverSurface can skip its own Escape handler in auto mode (the browser owns it). - Exports `PopoverAuto` and `usePopoverAuto` from the popover subpath. - Updates the Nested Storybook story to use PopoverAuto, where browser popover-stack semantics keep ancestor surfaces open when a descendant popover opens, and dismiss the ancestor chain on outside interaction. Tests, type-check, lint, and api-report all pass.

…om usePopover/usePopoverAuto

…er the auto Popover surface (re)mounts

…PopoverAuto

…d comparison

mainframev self-assigned this Apr 20, 2026

mainframev added Component: Popover Component: PopoverSurface Area: Positioning Headless labels Apr 20, 2026

microsoft-github-policy-service Bot added the PR: API Modified label Apr 20, 2026

mainframev force-pushed the feat/headless-popover-v2 branch from f26ae3e to 22f36ba Compare April 20, 2026 00:55

mainframev force-pushed the feat/headless-popover-v2 branch from 22f36ba to e9fef9d Compare April 20, 2026 01:46

mainframev force-pushed the feat/headless-popover-v2 branch 12 times, most recently from 58218ca to c32d139 Compare April 22, 2026 10:30

mainframev changed the title ~~WIP: feat(react-headless-components-preview): add Popover & positioning~~ feat(react-headless-components-preview): add Popover & positioning Apr 22, 2026

mainframev marked this pull request as ready for review April 22, 2026 10:42

mainframev requested review from a team as code owners April 22, 2026 10:42

mainframev requested a review from dmytrokirpa April 22, 2026 10:47

mainframev force-pushed the feat/headless-popover-v2 branch from c32d139 to 4774cce Compare April 22, 2026 12:21

mainframev requested a review from a team as a code owner April 22, 2026 12:21

mainframev force-pushed the feat/headless-popover-v2 branch from 4774cce to 0022e71 Compare April 22, 2026 12:57

mainframev marked this pull request as draft April 23, 2026 13:18

dmytrokirpa reviewed Apr 23, 2026

View reviewed changes

mainframev changed the title ~~feat(react-headless-components-preview): add Popover & positioning~~ WIP: feat(react-headless-components-preview): add Popover & positioning Apr 24, 2026

mainframev force-pushed the feat/headless-popover-v2 branch 3 times, most recently from 773c5b6 to 6aea7b4 Compare April 27, 2026 15:50

mainframev added 8 commits April 27, 2026 18:24

feat(react-headless-components-preview): add headless Popover built o…

a337d93

…n native CSS anchor positioning

docs(react-headless-components-preview): add Popover Storybook stories

9f3b6b9

docs(react-headless-components-preview): add Positioning concept Stor…

9c9b1a8

…ybook stories

refactor(react-headless-components-preview): rebuild usePositioning o…

31da14c

…n spec-pure CSS anchor positioning

docs(headless): add Popover spec

a57bdf6

chore(react-dialog): remove accidentally committed duplicate file

583dd25

refactor(react-headless-components-preview): remove custom trapFocus …

b62dcc6

…and unsupported positioning props

docs(react-headless-components-preview): align Popover spec with iter…

cdbbfcf

…ation-1 strip-down

mainframev force-pushed the feat/headless-popover-v2 branch from b5ae6c5 to 13c85ad Compare April 27, 2026 16:26

mainframev changed the title ~~WIP: feat(react-headless-components-preview): add Popover & positioning~~ feat(react-headless-components-preview): add Popover & positioning Apr 27, 2026

mainframev added 6 commits April 27, 2026 19:35

chore: adjust stories popover paths to use sub-paths

1de9ff5

test(react-headless-components-preview): switch usePositioning style …

dde2f6a

…assertions to toHaveStyle

chore: format

c05836b

chore: change files

be4f4ed

refactor(react-headless-components-preview): drop unused ref param fr…

90a044d

…om usePopover/usePopoverAuto

mainframev force-pushed the feat/headless-popover-v2 branch from 6e877df to ce13da9 Compare April 27, 2026 17:36

mainframev marked this pull request as ready for review April 27, 2026 19:58

mainframev added 3 commits April 27, 2026 22:28

fix(react-headless-components-preview): attach toggle listener whenev…

6147a9e

…er the auto Popover surface (re)mounts

refactor(react-headless-components-preview): split usePopover and use…

0e1d032

…PopoverAuto

docs(react-headless-components-preview): shorten manual-vs-auto neste…

68886c7

…d comparison

mainframev force-pushed the feat/headless-popover-v2 branch from ce13da9 to 68886c7 Compare April 27, 2026 20:28

chore: update api md

11dfb90

mainframev marked this pull request as draft April 28, 2026 14:21

	const result = usePositioning(options);
	const result = usePositioning(options) as unknown as { current: PositioningReturn };

	expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');
	expect(node).toHaveStyle({ positionArea: 'block-end span-inline-end' });


		const positioning = usePositioning(resolvePositioningShorthand(props.positioning));

		useOnClickOutside({

Conversation

mainframev commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Feature with v9 @fluentui/react-popover

Related Issue(s)

Uh oh!

github-actions Bot commented Apr 20, 2026

Uh oh!

github-actions Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Bundle size report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mainframev commented Apr 20, 2026 •

edited

Loading

Feature with v9 `@fluentui/react-popover`

github-actions Bot commented Apr 20, 2026 •

edited

Loading

mainframev Apr 23, 2026 •

edited

Loading

mainframev Apr 23, 2026 •

edited

Loading

mainframev Apr 27, 2026 •

edited

Loading